Hello, I recently needed a JWK middleware for my projects, but I figured contributing it to hono has the potential to save me and others a lot of time.

Middleware Features:

• Set options.keys to a static array of public keys JsonWebKey[] in code.
• Set options.keys to an async function that returns a Promise<JsonWebKey[]> for flexibility
• Set options.jwks_uri to fetch JWKs from a URI, after which it appends those fetched keys to provided keys if any
• Set an optional init parameter (only used for jwks_uri)—useful if your host supports caching through custom init options.

Added extra:

• Added JwtHeaderRequiresKid exception. Since the middleware requires presence of a kid field in the header in order to select the correct key.
• Added Jwt.verifyFromJwks util function (batteries included).

Addressed issues:

• Support JWKs validation #3658
• Support for JWT with JWKS #2589
• Support for asymmetric JWT validation (e.g. Auth0 or Clerk) #672

Other code changes:

• Typescript-extended JsonWebKey to have kid?: string (This is a standard: https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.4)
• Added kid?: string to TokenHeader
• Fixed a bug in Jwt.sign(payload, privateKey, alg) where privateKey.alg was always ignored and only alg parameter was considered.

Suggestion: Removal of the default 'HS256' value from Jwt.sign and make alg optional, so that if neither privateKey.alg nor alg is defined, throw an error. My 'philosophy' for this is that it would be misleading for hono to display = 'HS256' when the privateKey can internally have a different algorithm, such as when it is of type JsonWebKey or CryptoKey (Though we only care about JsonWebKey here). Making alg a "fallback" explicit parameter could be better.

Example Usage:

Using jwks_uri

import { jwk } from "hono/jwk";
app.use("/backend-api/*", jwk({ jwks_uri: "https://example-backend.hono.dev/.well-known/jwks.json" }));

Using jwks_uri and an optional init

import { jwk } from "hono/jwk";
app.use("/backend-api/*", jwk({
  jwks_uri: "https://example.hono.dev/.well-known/jwks.json"
}, {
  headers: {
    "My-Custom-Header": "Hello Hono!"
  },
  cf: { cacheTtl: 3600, cacheEverything: true } // Only for Cloudflare Workers
}));

Using keys from an array

[
  {
    "kid": "VpNx_Ar8pXsh50UjqBD_XtYLj4k9Z72iakeOQFJYIpg",
    "kty": "RSA",
    "use": "sig",
    "alg": "RS256",
    "e": "AQAB",
    "n": "4anIpNGZ-C5rJfRty8qQt8wTheFDj9wchPA..."
  },
  {
    "kid": "Rw6zp1oTEbQ9qUIFnhHGadtstXhKYrCmkqgkNEG8uUc",
    "kty": "RSA",
    "use": "sig",
    "alg": "RS256",
    "e": "AQAB",
    "n": "vKetN8i4_ORAWAUVR1pCjVMFkNzwC1Qjy..."
  }
]

import keys from './keys.json';
import { jwk } from "hono/jwk";
app.use("/backend-api/*", jwk({ keys: keys }));

Using keys as an async function (custom logic / caching)

$router.use("/auth/*", jwk({
  keys: async () => {
    /* ... Custom caching logic ... */
    return cached_response.keys;
  }
}));

Tests:

I adapted a lot from JWT's own units tests to make sure some basic JWT validation exists, then added the actual validation for the JWK middleware's own functionality which is mostly: (1) getting keys through various methods, (2) selecting the appropriate JWK based on kid (without fully decoding the JWT—only the header), and then (3) verifying using the utility Jwt.verify. Step 2 and 3 are done by Jwt.verifyFromJwks.

JWK Middleware Test

hono> npx src/middleware/jwk/index.test.ts

 DEV  v2.1.1 V:/Repos/hono
      Coverage enabled with v8

 ✓ src/middleware/jwk/index.test.ts (16)
   ✓ JWK (16)
     ✓ Credentials in header (10)
       ✓ Should not authorize requests with missing access token
       ✓ Should authorize from a static array passed to options.keys (key 1)
       ✓ Should authorize from a static array passed to options.keys (key 2)
       ✓ Should authorize with Unicode payload from a static array passed to options.keys
       ✓ Should authorize from a function passed to options.keys
       ✓ Should authorize from a URI remotely fetched from options.jwks_uri
       ✓ Should not authorize requests with invalid Unicode payload in header
       ✓ Should not authorize requests with malformed token structure in header
       ✓ Should not authorize requests without authorization in nested JWK middleware
       ✓ Should authorize requests with authorization in nested JWK middleware
     ✓ Credentials in cookie (5)
       ✓ Should not authorize requests with missing access token
       ✓ Should authorize from a static array passed to options.keys
       ✓ Should authorize with Unicode payload from a static array passed to options.keys
       ✓ Should not authorize requests with invalid Unicode payload in cookie
       ✓ Should not authorize requests with malformed token structure in cookie
     ✓ Error handling with `cause` (1)
       ✓ Should not authorize

 Test Files  1 passed (1)
      Tests  16 passed (16)

Full Test

hono> npm test
...
...
...
 Test Files  9 passed (9)
      Tests  415 passed | 3 skipped (418)

• [✅] Add tests (src/middleware/jwk/index.test.ts)
• [✅] Run tests (Above)
• [✅] bun run format:fix && bun run lint:fix to format the code (Done)
• [✅] Add TSDoc/JSDoc to document the code (src/middleware/jwk/jwk.ts)

Feel free to contribute more unit tests, extend and/or modify for the better.